<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>linear_interpn</title>
  </head>
  <body bgcolor="#FFFFFF">
    <center>Scilab Function</center>
    <div align="right">Last update : 11/03/2005</div>
    <p>
      <b>linear_interpn</b> - n dimensional linear interpolation</p>
    <h3>
      <font color="blue">Calling Sequence</font>
    </h3>
    <dl>
      <dd>
        <tt>vp = linear_interpn(xp1,xp2,..,xpn, x1, ..., xn, v [,out_mode])</tt>
      </dd>
    </dl>
    <h3>
      <font color="blue">Parameters</font>
    </h3>
    <ul>
      <li>
        <tt>
          <b>xp1, xp2, .., xpn</b>
        </tt>: real vectors (or matrices) of same size</li>
      <li>
        <tt>
          <b>x1 ,x2, ..., xn</b>
        </tt>:  strictly increasing row vectors (with at least 2 components)
               defining the n dimensional interpolation grid</li>
      <li>
        <tt>
          <b>v</b>
        </tt>:  vector (case n=1), matrix (case n=2) or hypermatrix (case n &gt; 2) with the
                 values of the underlying interpolated function at the grid points.</li>
      <li>
        <tt>
          <b>out_mode</b>
        </tt>: (optional) string defining the evaluation outside the grid (extrapolation)</li>
      <li>
        <tt>
          <b>vp</b>
        </tt>:  vector or matrix of same size than <tt>
          <b>xp1, ..., xpn</b>
        </tt>
      </li>
    </ul>
    <h3>
      <font color="blue">Description</font>
    </h3>
    <p>
    Given a n dimensional grid defined by the n vectors <tt>
        <b>x1 ,x2, ..., xn</b>
      </tt> and the
    values <tt>
        <b>v</b>
      </tt> of a function (says <em>f</em>) at the grid points :
    </p>
    <pre>
      v(i1,i2,...,in) = f(x1(i1),x2(i2), ..., xn(in))
         </pre>
    <p>
    this function computes the linear interpolant of <em>f</em> from the grid (called <em>s</em>
    in the following) at the points which coordinates are defined by the vectors (or matrices) 
    <tt>
        <b>xp1, xp2, ..., xpn</b>
      </tt>:
    </p>
    <pre>
   vp(i) = s(xp1(i),xp2(i), ..., xpn(i))

   or vp(i,j) = s(xp1(i,j),xp2(i,j), ..., xpn(i,j)) in case the xpk are matrices
         </pre>
    <p>
    The <tt>
        <b>out_mode</b>
      </tt> parameter set the evaluation rule for extrapolation: if we note 
    <em>Pi=(xp1(i),xp2(i),...,xpn(i))</em> then <tt>
        <b>out_mode</b>
      </tt> defines the
    evaluation rule when:
    </p>
    <pre>
   P(i) not in  [x1(1) x1($)] x [x2(1) x2($)] x ... x [xn(1) xn($)]
         </pre>
    <p>
    The different choices are:
    </p>
    <dd>
      <li>
        <b>
          <font color="maroon">"by_zero"</font>
        </b>: an extrapolation by zero is done</li>
      <li>
        <b>
          <font color="maroon">"by_nan"</font>
        </b>: extrapolation by Nan</li>
      <li>
        <b>
          <font color="maroon">"C0"</font>
        </b>: the extrapolation is defined as follows:<pre>
     s(P) = s(proj(P)) where proj(P) is nearest point from P 
                       located on the grid boundary.
         </pre>
      </li>
      <li>
        <b>
          <font color="maroon">"natural"</font>
        </b>: the extrapolation is done by using the nearest n-linear patch from the point.</li>
      <li>
        <b>
          <font color="maroon">"periodic"</font>
        </b>: <tt>
          <b>s</b>
        </tt> is extended by periodicity.</li>
    </dd>
    <h3>
      <font color="blue">Examples</font>
    </h3>
    <pre>
// example 1 : 1d linear interpolation
x = linspace(0,2*%pi,11);
y = sin(x);
xx = linspace(-2*%pi,4*%pi,400)';
yy = linear_interpn(xx, x, y, "periodic");
xbasc()
plot2d(xx,yy,style=2)
plot2d(x,y,style=-9, strf="000")
xtitle("linear interpolation of sin(x) with 11 interpolation points")

// example 2 : bilinear interpolation
n = 8;
x = linspace(0,2*%pi,n); y = x;
z = 2*sin(x')*sin(y);
xx = linspace(0,2*%pi, 40);
[xp,yp] = ndgrid(xx,xx);
zp = linear_interpn(xp,yp, x, y, z);
xbasc()
plot3d(xx, xx, zp, flag=[2 6 4])
[xg,yg] = ndgrid(x,x);
param3d1(xg,yg, list(z,-9*ones(1,n)), flag=[0 0])
xtitle("Bilinear interpolation of 2sin(x)sin(y)")
legends("interpolation points",-9,1)
xselect()

// example 3 : bilinear interpolation and experimentation
//             with all the outmode features
nx = 20; ny = 30;
x = linspace(0,1,nx);
y = linspace(0,2, ny);
[X,Y] = ndgrid(x,y);
z = 0.4*cos(2*%pi*X).*cos(%pi*Y);
nxp = 60 ; nyp = 120;
xp = linspace(-0.5,1.5, nxp);
yp = linspace(-0.5,2.5, nyp);
[XP,YP] = ndgrid(xp,yp);
zp1 = linear_interpn(XP, YP, x, y, z, "natural");
zp2 = linear_interpn(XP, YP, x, y, z, "periodic");
zp3 = linear_interpn(XP, YP, x, y, z, "C0");
zp4 = linear_interpn(XP, YP, x, y, z, "by_zero");
zp5 = linear_interpn(XP, YP, x, y, z, "by_nan");
xbasc()
subplot(2,3,1)
   plot3d(x, y, z, leg="x@y@z", flag = [2 4 4])
   xtitle("initial function 0.4 cos(2 pi x) cos(pi y)")
subplot(2,3,2)
   plot3d(xp, yp, zp1, leg="x@y@z", flag = [2 4 4])
   xtitle("Natural")
subplot(2,3,3)
   plot3d(xp, yp, zp2, leg="x@y@z", flag = [2 4 4])
   xtitle("Periodic")
subplot(2,3,4)
   plot3d(xp, yp, zp3, leg="x@y@z", flag = [2 4 4])
   xtitle("C0")
subplot(2,3,5)
   plot3d(xp, yp, zp4, leg="x@y@z", flag = [2 4 4])
   xtitle("by_zero")
subplot(2,3,6)
   plot3d(xp, yp, zp5, leg="x@y@z", flag = [2 4 4])
   xtitle("by_nan")
xselect()


// example 4 : trilinear interpolation (see splin3d help
//             page which have the same example with
//             tricubic spline interpolation)
getf("SCI/demos/interp/interp_demo.sci") 
func =  "v=(x-0.5).^2 + (y-0.5).^3 + (z-0.5).^2";
deff("v=f(x,y,z)",func);
n = 5; 
x = linspace(0,1,n); y=x; z=x;
[X,Y,Z] = ndgrid(x,y,z);
V = f(X,Y,Z);
// compute (and display) the linear interpolant on some slices
m = 41;
dir = ["z="  "z="  "z="  "x="  "y="];
val = [ 0.1   0.5   0.9   0.5   0.5];
ebox = [0 1 0 1 0 1];

XF=[]; YF=[]; ZF=[]; VF=[];
for i = 1:length(val)
   [Xm,Xp,Ym,Yp,Zm,Zp] = slice_parallelepiped(dir(i), val(i), ebox, m, m, m);
   Vm = linear_interpn(Xm,Ym,Zm, x, y, z, V);
   [xf,yf,zf,vf] = nf3dq(Xm,Ym,Zm,Vm,1);
   XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf]; VF = [VF vf]; 
   Vp =  linear_interpn(Xp,Yp,Zp, x, y, z, V);
   [xf,yf,zf,vf] = nf3dq(Xp,Yp,Zp,Vp,1);
   XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf]; VF = [VF vf]; 
end
nb_col = 128;
vmin = min(VF); vmax = max(VF);
color = dsearch(VF,linspace(vmin,vmax,nb_col+1));
xset("colormap",jetcolormap(nb_col));
xbasc()
xset("hidden3d",xget("background"))
colorbar(vmin,vmax)
plot3d(XF, YF, list(ZF,color), flag=[-1 6 4])
xtitle("tri-linear interpolation of "+func)
xselect()
 </pre>
    <h3>
      <font color="blue">See Also</font>
    </h3>
    <p>
      <a href="interpln.htm">
        <tt>
          <b>interpln</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="splin.htm">
        <tt>
          <b>splin</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="splin2d.htm">
        <tt>
          <b>splin2d</b>
        </tt>
      </a>,&nbsp;&nbsp;<a href="splin3d.htm">
        <tt>
          <b>splin3d</b>
        </tt>
      </a>,&nbsp;&nbsp;</p>
    <h3>
      <font color="blue">Author</font>
    </h3>
    <p>
    B. Pincon
  </p>
  </body>
</html>
